dotenv-expand

dotenv-expand

Dotenv-expand adds variable expansion on top of dotenv. If you find yourself needing to expand environment variables already existing on your machine, then dotenv-expand is your tool.

Install

# Install locally (recommended)
npm install dotenv-expand --save

Or installing with yarn? yarn add dotenv-expand

Usage

Create a .env file in the root of your project:

PASSWORD="s1mpl3"
DB_PASS=$PASSWORD

As early as possible in your application, import and configure dotenv and then expand dotenv:

var dotenv = require('dotenv')
var dotenvExpand = require('dotenv-expand')

var myEnv = dotenv.config()
dotenvExpand.expand(myEnv)

console.log(process.env)

That's it. process.env now has the expanded keys and values you defined in your .env file.

Preload

You can use the --require (-r) command line option to preload dotenv & dotenv-expand. By doing this, you do not need to require and load dotenv or dotenv-expand in your application code. This is the preferred approach when using import instead of require.

$ node -r dotenv-expand/config your_script.js

The configuration options below are supported as command line arguments in the format dotenv_config_<option>=value

$ node -r dotenv-expand/config your_script.js dotenv_config_path=/custom/path/to/your/env/vars

Additionally, you can use environment variables to set configuration options. Command line arguments will precede these.

$ DOTENV_CONFIG_<OPTION>=value node -r dotenv-expand/config your_script.js

$ DOTENV_CONFIG_ENCODING=latin1 node -r dotenv-expand/config your_script.js dotenv_config_path=/custom/path/to/.env

Examples

See tests/.env for simple and complex examples of variable expansion in your .env file.

Documentation

DotenvExpand exposes one function:

• expand

Expand

expand will expand your environment variables.

const dotenv = {
  parsed: {
    BASIC: 'basic',
    BASIC_EXPAND: '${BASIC}',
    BASIC_EXPAND_SIMPLE: '$BASIC'
  }
}

const obj = dotenvExpand.expand(dotenv)

console.log(obj)

Options

ignoreProcessEnv

Default: false

Turn off writing to process.env.

const dotenv = {
  ignoreProcessEnv: true,
  parsed: {
    SHOULD_NOT_EXIST: 'testing'
  }
}
const obj = dotenvExpand.expand(dotenv).parsed

console.log(obj.SHOULD_NOT_EXIST) // testing
console.log(process.env.SHOULD_NOT_EXIST) // undefined

FAQ

What rules does the expansion engine follow?

The expansion engine roughly has the following rules:

• $KEY will expand any env with the name KEY
• ${KEY} will expand any env with the name KEY
• \$KEY will escape the $KEY rather than expand
• ${KEY:-default} will first attempt to expand any env with the name KEY. If not one, then it will return default

You can see a full list of examples here.

Contributing Guide

See CONTRIBUTING.md

CHANGELOG

See CHANGELOG.md

Who's using dotenv-expand?

These npm modules depend on it.